This page last changed on Jul 26, 2006 by stephen fenech.
Transport providers can be configured in 3 ways -
- Using an endpoint Uri that defines the scheme and connection information for the transport, such as tcp://localhost:12345. See Mule Endpoint URIs for more information. The URI consists of the protocol followed by transport specific information and then zero or more parameters to set as properties on the connector.
- Defining a connector configuration in Mule xml, Spring or any other supported configuration.
- Transport provider properties can be set on endpoints to customise the transport behaviour for a single endpoint instance.
The actual configuration parameters for each transport type are described in the Transports Guide for each particular transport. The following describes the common properties for all transports.
Standard Connector Properties
Property |
Description |
Default |
Required |
name |
The identifying name of the connector |
|
Yes |
exceptionListener |
The exception listener to use when errors occur in the connector. |
org.mule.impl. DefaultExceptionStrategy |
Yes |
receiverThreadingProfile |
This defines the threading properties and WorkManager to use when receiving events from the connector |
The defaultReceiverThreadingProfile set on the Mule Configuration |
Yes |
dispatcherThreadingProfile |
This defines the threading properties and WorkManager to use when dispatching events from the connector |
The defaultDispatcherThreadingProfile set on the Mule Configuration |
Yes |
disposeDispatcherOnCompletion |
Determines whether the connector caches a MessageDispatcher once one it is created for an endpoint or if a new one should be created for each dispatch request |
false |
Yes |
connectionStrategy |
Is the object responsible for controlling how connection failures and retries are handled. The connectionStrategy can attempt to make a connection based on frequency, retry attempts, Jmx, or some other trigger. |
org.mule.providers. SingleAttemptConnectionStrategy |
Yes |
serviceOverrides |
Is a map of service configuration values that can be used to override the default configuration for this transport. Service Overrides are described earlier in this document |
|
No |
For information about specific properties for a particular transport provider see the Transports Guide.
Connection Strategies
Connection strategies are used to configure how a connector behaves when it connection fails. Different strategies can be used to control how a reconnection is made based on reties, frequency, exceptions occurred or other factors such as only allowing a reconnect from Jmx.
A connection Strategy is configured on the connector using the <connection-strategy> element. When a <connection-strategy> element is added to a connector the strategy is applied to inbound and outbound connections. If you require different behaviour for inbound and outbound connections on the same connector you need to configure two connectors to handle inbound and outbound connections differently. For example, to configure a Tcp connector that will try to connect 3 times every 2 seconds if the connection is lost -
<connector name="tcp" className="org.mule.providers.tcp.TcpConnector">
<connection-strategy className="org.mule.providers.SimpleRetryConnectionStrategy">
<properties>
<property name="retryCount" value="3"/>
<property name="frequency" value="2000"/>
</properties>
<connection-strategy/>
</connector>
You can set a default connection strategy for all connectors on a Mule instance by setting the strategy in the <mule-environment-properties> element, i.e.
<mule-environment-properties>
<connection-strategy className="org.mule.providers.SimpleRetryConnectionStrategy">
<properties>
<property name="retryCount" value="3"/>
<property name="frequency" value="2000"/>
</properties>
<connection-strategy/>
</mule-environment-properties>
Customising Connection Strategies
Mule comes with a few basic connection strategies such as the the SimpleRetryConnectionStrategy shown above. However, you may need to implement your own. The UMOConnectionStrategy is an interface with one method -
public void doConnect(UMOConnectable connectable) throws FatalConnectException;
This method should attempt to call connect() on the UMOConnectable object, until the connection works or the connection policy implemented by the custom UMOConnectionStrategy fails. If the connection fails a FatalConnectException should be thrown to tell Mule that it cannot connect. No other exceptions including RuntimeExceptions should be thrown.
Connector Service Descriptors
Each transport has a service descriptor that describes what classes are used to construct the transport. The file is located in META-INF/services/org/mule/providers and the file has the same name as the transport protocol i.e. META-INF/services/org/mule/providers/tcp.
Using the TCP transport provider as an examples the file looks like -
Property |
Description |
Required |
connector |
The class name of the UMOConnector implementation to use |
Yes if no connector.factory |
connector.factory |
The class name of the factory that can be used to construct the UMOConnector instance if the 'connector' property is not set. The factory class must implement org.mule.util.ObjectFactory. |
No |
dispatcher.factory |
The classname of the class that implements UMOMessageDispatcherFactory, which is used to construct UMOMessageDispatcher instances for this transport. If the transport provider only supports inbound communication this property is not set |
No |
message.receiver |
The classname of the class that implements UMOMessageReceiver, which is used to register message listeners with the transport. If the transport provider only supports outbound communication this property is not set |
No |
transaction.factory |
If this transport is transactional the property defines the class name of the UMOTransactionFactory implementation use to create transactions for this transport |
No |
message.adapter |
The class name of the UMOMessageAdapter implementation used to provide generic access to information about the underlying message type for this transport |
Yes |
inbound.transformer |
The default inbound transformer for this transport. This transformer will be used to transform incoming messages if there is no transformer configured on the endpoint using this transport. If the endpoint is inbound and it defines a transformer this value will be ignored. |
No |
outbound.transformer |
The default outbound transformer for this transport. This transformer will be used to transform outgoing messages if there is no transformer configured on the endpoint using this transport. If the endpoint is outbound and it defines a transformer this value will be ignored. |
No |
response.transformer |
The default response transformer for this transport. Transports may or may no use this transformer depending on whether the transport supports sending responses back from a request; such as http. This transformer will be used to transform response messages if there is no transformer configured on the response router for the current component. |
No |
endpoint.builder |
The endpoint builder used to configure MuleEndpointURI instances for the transport. It is responsible for extracting information from URIs in a way understood by this connector. For example, the URI jms://topic:datafeed will be processed by the ResourceNameEndpointBuilder such that the endpoint address will be 'datafeed' and 'topic' will be set as the resourceInfo for the endpoint telling the Jms connector to use/create a topic called 'datafeed'. |
Yes |
service.finder |
Some transport providers such as SOAP provide multiple, vendor-specific implementations of the transport such as Axis, Glue or XFire. The service finder class can be used to determine which implementation to use, often based on what's on the classpath. so for the endpoint URI soap:http//localhost/8080/services the SOAPServiceFinder will be used to see if Axis or Glue is on the classpath and will constuct the service accordingly. |
No |
service.error |
If for any reason a transport connector cannot be constructed using an endpoint URI, an error message can be set here and a ConnectorFactoryException will be thrown with this message if an attempt is made to construct the connector from an URI (instead of configuring the connector explicitly in configuration) |
No |
When an endpoint URI is processed by Mule, it's service descriptor is located using the endpoint protocol and the descriptor along with the information on the URI are used to create a connector and endpoint instance.
Overriding Service Properties
Each Mule transport has a Connector Service Descriptor for each protocol the transport supports that contains some of the properties listed above. Users can override any of these settings for a particular transports so that it's behaviour can be customised to suit a particular usage. For example the FileConnector reads individual files from a directory, but a developer could write a custom UMOMessageReceiver for the file connector to just read changes from an existing file.
Every connector has a serviceOverrides property which is a Map containing one or more of the service properties listed above. Continuing with the custom File Receiver example, a developer can override the 'message.reciever' Connector Service Descriptor property.
<connector name="myFileConnector" className="org.mule.providers.file.FileConnector">
<properties>
...
<map name="serviceOverrides">
<property name="message.receiver" value="com.foo.MyFileReceiver"/>
</map>
</properties>
</connector>
Setting Default Connector values
For some transports its easy to set all configuration info for the transport in URI i.e. tcp://localhist:12345. For other transports such as Jms, the developer needs to set lots of configuration parameters to create the connection and it becomes difficult to set these parameters on the URI. One option is to pre-configre all connectors in a configuration file, which is fine for some scenarios, but there is also another option.
Mule allows for default properties to be defined for connectors that will be used in absence of the properties being set directly. The properties themselves are set using the name of the property for the connector pre-pended with the connector protocol. For example, to set a default value for the Jms jndiInitialFactory property -
<environment-properties>
<property name="jms.jndiInitialFactory"
value="org.codehaus.activemq.jndi.ActiveMQInitialContextFactory"/>
</environment-properties>
or
MuleManager.getInstance.setProperty("jms.jndiInitialFactory",
"org.codehaus.activemq.jndi.ActiveMQInitialContextFactory");
These properties can be set on the MuleManager or Client.
For a more complete example see the Mule Cookbook: Configuring Multiple Jms Clients
Writing your own Transport
If you want to implement a custom Transport for Mule see Writing Mule Transport Providers.
|